home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / DString.3 < prev    next >
Text File  |  1994-09-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_DStringInit(3)   Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_DStringInit, Tcl_DStringAppend,
  12.      Tcl_DStringAppendElement, Tcl_DStringStartSublist,
  13.      Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue,
  14.      Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult - mani-
  15.      pulate dynamic strings
  16.  
  17. SYNOPSIS
  18.      #include <tcl.h>
  19.  
  20.      Tcl_DStringInit(_d_s_P_t_r)
  21.  
  22.      char *
  23.      Tcl_DStringAppend(_d_s_P_t_r, _s_t_r_i_n_g, _l_e_n_g_t_h)
  24.  
  25.      char *
  26.      Tcl_DStringAppendElement(_d_s_P_t_r, _s_t_r_i_n_g)
  27.  
  28.      Tcl_DStringStartSublist(_d_s_P_t_r)
  29.  
  30.      Tcl_DStringEndSublist(_d_s_P_t_r)
  31.  
  32.      int
  33.      Tcl_DStringLength(_d_s_P_t_r)
  34.  
  35.      char *
  36.      Tcl_DStringValue(_d_s_P_t_r)
  37.  
  38.      Tcl_DStringTrunc(_d_s_P_t_r, _n_e_w_L_e_n_g_t_h)
  39.  
  40.      Tcl_DStringFree(_d_s_P_t_r)
  41.  
  42.      Tcl_DStringResult(_i_n_t_e_r_p, _d_s_P_t_r)
  43.  
  44. ARGUMENTS
  45.      Tcl_DString   *_d_s_P_t_r      (in/out)  Pointer   to   structure
  46.                                          that is used to manage a
  47.                                          dynamic string.
  48.  
  49.      char          *_s_t_r_i_n_g     (in)      Pointer to characters to
  50.                                          add to dynamic string.
  51.  
  52.      int           _l_e_n_g_t_h      (in)      Number   of   characters
  53.                                          from  string  to  add to
  54.                                          dynamic string.  If  -1,
  55.                                          add all characters up to
  56.                                          null terminating charac-
  57.                                          ter.
  58.  
  59.      int           _n_e_w_L_e_n_g_t_h   (in)      New length  for  dynamic
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_DStringInit(3)   Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74.                                          string,   not  including
  75.                                          null terminating charac-
  76.                                          ter.
  77. _________________________________________________________________
  78.  
  79.  
  80. DESCRIPTION
  81.      Dynamic strings provide a mechanism for  building  up  arbi-
  82.      trarily long strings by gradually appending information.  If
  83.      the dynamic string is short then there  will  be  no  memory
  84.      allocation  overhead;  as the string gets larger, additional
  85.      space will be allocated as needed.
  86.  
  87.      Tcl_DStringInit initializes a dynamic string to zero length.
  88.      The  Tcl_DString  structure  must have been allocated by the
  89.      caller.  No assumptions are made about the current state  of
  90.      the  structure; anything already in it is discarded.  If the
  91.      structure has been used previously,  Tcl_DStringFree  should
  92.      be  called first to free up any memory allocated for the old
  93.      string.
  94.  
  95.      Tcl_DStringAppend adds new information to a dynamic  string,
  96.      allocating  more memory for the string if needed.  If _l_e_n_g_t_h
  97.      is less than zero then everything in _s_t_r_i_n_g is  appended  to
  98.      the  dynamic  string;  otherwise _l_e_n_g_t_h specifies the number
  99.      of bytes to append.  Tcl_DStringAppend returns a pointer  to
  100.      the  characters  of  the new string.  The string can also be
  101.      retrieved from the _s_t_r_i_n_g field of  the  Tcl_DString  struc-
  102.      ture.
  103.  
  104.      Tcl_DStringAppendElement  is  similar  to  Tcl_DStringAppend
  105.      except  that  it  doesn't take a _l_e_n_g_t_h argument (it appends
  106.      all of _s_t_r_i_n_g) and it converts the string to a  proper  list
  107.      element  before  appending.  Tcl_DStringAppendElement adds a
  108.      separator space before the new list element unless  the  new
  109.      list element is the first in a list or sub-list (i.e. either
  110.      the current string is empty, or it contains the single char-
  111.      acter  ``{'',  or  the  last  two  characters of the current
  112.      string are  ``  {'').   Tcl_DStringAppendElement  returns  a
  113.      pointer to the characters of the new string.
  114.  
  115.      Tcl_DStringStartSublist  and  Tcl_DStringEndSublist  can  be
  116.      used  to create nested lists.  To append a list element that
  117.      is itself a  sublist,  first  call  Tcl_DStringStartSublist,
  118.      then  call Tcl_DStringAppendElement for each of the elements
  119.      in the sublist, then call Tcl_DStringEndSublist to  end  the
  120.      sublist.   Tcl_DStringStartSublist appends a space character
  121.      if    needed,     followed     by     an     open     brace;
  122.      Tcl_DStringAppendElement  appends  a close brace.  Lists can
  123.      be nested to any depth.
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_DStringInit(3)   Tcl Library Procedures                   7.0
  137.  
  138.  
  139.  
  140.      Tcl_DStringLength is a macro that returns the current length
  141.      of  a  dynamic  string  (not  including the terminating null
  142.      character).  Tcl_DStringValue is a   macro  that  returns  a
  143.      pointer to the current contents of a dynamic string.
  144.  
  145.      Tcl_DStringTrunc truncates  a  dynamic  string  to  a  given
  146.      length.   It has no effect if the string was already smaller
  147.      than  _n_e_w_L_e_n_g_t_h.   This  procedure  does  not  free  up  the
  148.      string's  storage  space, even if the string is truncated to
  149.      zero length,  so  Tcl_DStringFree  will  still  need  to  be
  150.      called.
  151.  
  152.      Tcl_DStringFree should be called when you're finished  using
  153.      the  string.   It frees up any memory that was allocated for
  154.      the string and reinitializes the string's value to an  empty
  155.      string.
  156.  
  157.      Tcl_DStringResult sets the result of _i_n_t_e_r_p to the value  of
  158.      the dynamic string given by _d_s_P_t_r.  It does this by moving a
  159.      pointer from _d_s_P_t_r to _i_n_t_e_r_p->_r_e_s_u_l_t.  This saves  the  cost
  160.      of   allocating   new   memory   and   copying  the  string.
  161.      Tcl_DStringResult also reinitializes the dynamic  string  to
  162.      an empty string.
  163.  
  164.  
  165. KEYWORDS
  166.      append, dynamic string, free, result
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.